home *** CD-ROM | disk | FTP | other *** search
/ Easy Personal Web Page / Easy Personal Web Page.iso / EMAIL / PEGASUS / PMIF.TXT < prev    next >
Text File  |  1994-08-26  |  10KB  |  206 lines
  1.                  Pegasus Mail Electronic Mail System, 
  2.         Copyright (c) 1990-94 David Harris, all rights reserved
  3.  
  4.         Pegasus Mail - Local Delivery System Interface Services
  5.  
  6.  
  7. Starting with version 3.2 for DOS and 1.2 for Windows, Pegasus Mail
  8. provides a programmatic mechanism for setting the following internal
  9. system information required for local delivery at runtime:
  10.  
  11.    A: The name of the user at the current workstation
  12.    B: The path to a specified user's new mail directory
  13.    C: The delivery path for outgoing mail to a specified user
  14.  
  15. A mechanism is also provided which allows Pegasus Mail's local user list 
  16. to be substituted with any programmatic service appropriate to a site.
  17.  
  18. For the path lookup functions (B and C), two methods are provided - the 
  19. first simply involves the use of simple static paths which Pegasus Mail 
  20. will use in preference to its default paths. The strings specifying these 
  21. paths may use the same substitution values as any User-Defined Gateway 
  22. substitution string (for instance, "C:\MAIL\~8"). The more complex 
  23. approach involves the provision of working code, either as a program or 
  24. as a Windows DLL.
  25.  
  26.  
  27. Rationale
  28.  
  29. Why is this interface necessary? The simplest answer is because it
  30. allows Pegasus Mail to operate transparently on systems about which it
  31. may have no inherent internal understanding. By default, Pegasus Mail has
  32. intrinsic support only for Novell NetWare 3.x and earlier - all other
  33. systems are classed as "standalone". So, if you are a LAN Manager user,
  34. for example, Pegasus Mail will not be able to take advantage of any
  35. special services offered by that environment without some help. The
  36. external interface mechanism defined here allows you to "hook in" to the
  37. internal routines Pegasus Mail uses to identify users and paths with a
  38. minimal amount of coding, potentially providing a similar level of
  39. system integration to that Pegasus Mail enjoys natively with NetWare.
  40.  
  41. NetWare users may also want to use this interface if their system 
  42. requirements mean that the defaults Pegasus Mail uses are unacceptable 
  43. for some reason: as an example, if you have a small SYS: volume, you may 
  44. prefer Pegasus Mail to write new mail onto a volume other than SYS:. 
  45. Using this interface, all that is required to make this change (for 
  46. example to the USERS volume) is to add a PMSYSTEM.INI file which looks
  47. like this:
  48.  
  49.    [Pegasus Mail for DOS]
  50.    Static new mail directory path   = USERS:MAIL/~B
  51.    Static outgoing delivery path    = USERS:MAIL/~B
  52.  
  53. The mechanisms which have to be provided to implement these interfaces 
  54. necessarily vary for each version of Pegasus Mail: for the DOS version, a 
  55. program or programs should be provided, while the Windows version expects 
  56. a DLL with certain well-defined entry points. The exact values each 
  57. version of Pegasus Mail should use are defined in an INI file called 
  58. PMSYSTEM.INI, which must be located in the same directory as the .EXE 
  59. file it serves. PMSYSTEM.INI is described below.
  60.  
  61.  
  62. Pegasus Mail for DOS
  63.  
  64. To provide interface services for Pegasus Mail for DOS, you must supply
  65. a program or programs which accept certain fixed command-line parameters. 
  66. Pegasus Mail will invoke the program with a command-line switch which 
  67. indicates the service required, so a single program can perform multiple 
  68. duties if this is required. The program is passed the address of a memory 
  69. location inside Pegasus Mail into which the requested information must be 
  70. written, and an integer representing the maximum number of characters 
  71. which can be written into that location. The requirement that the program 
  72. write directly into Pegasus Mail's data segment necessitates considerable 
  73. care on the part of the programmer, and also implicitly requires the use 
  74. of a large memory model, since the location will be passed as a decimal 
  75. representation of a far pointer.
  76.  
  77. Pegasus Mail expects to find full pathnames to the program(s) it should
  78. run in a section entitled "[Pegasus Mail for DOS]" in PMSYSTEM.INI. The
  79. name of the entry associated with each command in this section is shown
  80. in the descriptions below:
  81.  
  82. The following service calls are defined:
  83.  
  84. 1: Obtain the specified user's new mail directory
  85.    Command line:
  86.       -n <username> <memory_location> <length>
  87.    Notes:
  88.       Pegasus Mail will run this program when it needs to know the
  89.       location of a specific user's new mail box. The new mail box
  90.       is where Pegasus Mail expects to find the user's PMAIL.INI
  91.       preferences file and where it should scan to find the user's
  92.       new mail.
  93.    PMSYSTEM.INI section entry:
  94.       "Query program for new mail directory"
  95.    Default:
  96.       On standalone systems - depends on configuration.
  97.       On NetWare systems - SYS:MAIL/<userid>
  98.  
  99. 2: Obtain the mail delivery path for a specified user
  100.    Command line:
  101.       -d <username> <memory_location> <length>
  102.    Notes:
  103.       Pegasus Mail will issue this command when it needs to know where
  104.       a file should be written for delivery to the specified user. It
  105.       is legitimate for the program to return the same path for all or
  106.       any subset of users (in the case where a smart system is being
  107.       used to process mail for all users). The current user must have
  108.       at least file create rights ([C] under NetWare) in this location.
  109.       Messages are always written into this location in RFC-822 format.
  110.    PMSYSTEM.INI section entry:
  111.       "Query program for delivery path"
  112.    Default:
  113.       On standalone systems - depends on configuration.
  114.       On NetWare systems - SYS:MAIL/<userid>
  115.  
  116. 3: Obtain the name of the user at the current workstation
  117.    Command line:
  118.       -u <memory_location> <length>
  119.    Notes:
  120.       This command is issued before any other processing inside the
  121.       program, and is usually only issued at initialization time. It
  122.       should return the username of the user at the current station.
  123.       (Note, this does NOT necessarily mean an address - a simple
  124.       username is expected).
  125.    PMSYSTEM.INI section entry:
  126.       "Query program for user name"
  127.    Default:
  128.       On standalone systems - value of PMUSER environment variable,
  129.          or the value entered by the user in response to a prompt.
  130.       On NetWare systems - the value returned by the NetWare API.
  131.  
  132. Example:
  133.  
  134.    You have two programs, LMUSER.EXE and LMPATH.EXE, which provide the
  135.    services Pegasus Mail needs. You would copy them into a specific
  136.    location (say for example R:\MAIL\EXE) and write your PMSYSTEM.INI so
  137.    that it looks like this:
  138.  
  139.    [Pegasus Mail for DOS]
  140.    Query program for new mail directory = R:\MAIL\EXE\LMPATH.EXE 
  141.    Query program for delivery path      = R:\MAIL\EXE\LMPATH.EXE 
  142.    Query program for user name          = R:\MAIL\EXE\LMUSER.EXE
  143.  
  144.    If you are working in an environment where it is acceptable to do
  145.    so, you may prefer to use '/' characters in paths instead of '\'s.
  146.  
  147.  
  148. Pegasus Mail for Windows
  149.  
  150. Pegasus Mail for windows supports the same static paths as the DOS
  151. version, using the same heading names. The programmatic interface
  152. services for Pegasus Mail for Windows must be provided in the form of a
  153. DLL. PMSYSTEM.INI will have a section entitled "[Pegasus Mail for
  154. Windows]", which will contain an entry specifying the name of the DLL to
  155. load, in the following format:
  156.  
  157.    [Pegasus Mail for Windows]
  158.    External interface routines DLL  = <path>
  159.  
  160. The DLL should export the following routines by name:
  161.  
  162.    int FAR PASCAL pmif_username (LPSTR username, long FAR *id, int maxlength);
  163.    int FAR PASCAL pmif_newmail_directory (const LPSTR username, LPSTR path,
  164.       int maxlength);
  165.    int FAR PASCAL pmif_delivery_path (const LPSTR username, LPSTR path,
  166.       int maxlength);
  167.  
  168. Each function should return 0 on success or 1 on failure. Other numeric
  169. return values are reserved for future use (to allow more elaborate
  170. error reporting).
  171.  
  172. These routines should operate as follows:
  173.  
  174.    pmif_username:
  175.       Should return the name of the user at the current workstation
  176.       in the string pointed to by "username". Optionally, the routine
  177.       may fill out the "id" parameter with a unique identifier for
  178.       this user; this equates to the user's Bindery Object ID under
  179.       NetWare, and if set to 1 tells Pegasus Mail that the user is
  180.       the system supervisor.
  181.  
  182.    pmif_newmail_directory:
  183.       Should return the fully-qualified path to the new mailbox for the
  184.       user specified. The path can be in DOS, NetWare or UNC format, but
  185.       be aware that some versions of the NetWare shell do not handle
  186.       fully-qualified NetWare paths (of the form SERVER/VOL:PATH/PATH)
  187.       properly.
  188.  
  189.    pmif_delivery_path:
  190.       Should return the fully-qualified path to the directory where
  191.       Pegasus Mail should write the file containing a message addressed
  192.       to the specified user. It is legal for the DLL to return the same
  193.       path for more than one, or all users.
  194.  
  195. The following notes apply to all these routines: at most "maxlength"
  196. bytes can be written into the target string, including the terminating
  197. nul; strings are expected to be standard C-style strings (nul-terminated,
  198. no leading length byte). Where a path is expected, Pegasus Mail can
  199. accept any valid DOS, Windows or NetWare format, but we recommend the use
  200. of UNC paths (in the general form \\SERVER\VOLUME\PATH...) in network
  201. environments and DOS paths in the standalone environment.
  202.  
  203. The DLL you provide is loaded at runtime and is not released until
  204. Pegasus Mail terminates.
  205.  
  206.